<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
      <!-- $Id: NT-Service-howto.html,v 1.7 2004/02/29 22:42:50 billbarker Exp $ -->
<!--
   Copyright 1999-2004 The Apache Software Foundation
 
   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at
 
       http://www.apache.org/licenses/LICENSE-2.0
 
   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
-->
 
  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
               
  <link rel="stylesheet" href="style.css">
  <title>Working with the Jakarta NT Service</title>
    
</head>
  <body>
<h1>Working with the Jakarta NT Service</h1>
<p>By Gal Shachor <tt>&lt;<a href="mailto:shachor@il.ibm.com">shachor@il.ibm.com</a>
   &gt;</tt><br>
   Modified by Dave Oxley &lt;<a href="mailto:dave@junglemoss.com">dave@junglemoss.com</a>
   &gt;<br>
</p>
<p>The Jakarta NT service is an executable that wraps the Tomcat servlet container
and executes it in the background as an NT service. To install it you will
need to:</p>
<ol>
  <li>Get a      hold on the NT executable (jk_nt_service.exe)</li>
  <ul>
    <li>Download       the executable from the win32/i386 directory  found 
 where you downloaded the       <a href="http://jakarta.apache.org/site/binindex.html">
    Tomcat binary       distribution.</a>
    For those using Netscape as your browser, try downloading       a zip 
version  of the file, if available. There can be problems using Netscape 
     to download DLL files.</li>
  </ul>
  <li>Customize      a properties file that provides the service with Tomcat 
 information      (wrapper.properties).</li>
  <ul>
    <li>Locate the wrapper.properties template file in your Tomcat conf/jk 
 directory.   </li>
    <li>Update       the wrapper.tomcat_home property to point at your tomcat 
 home.</li>
    <li>Update       the wrapper.java_home property to point at your Java 
 home.</li>
  </ul>
  <li>Install      jk_nt_service by running it with the -i flag.</li>
  <ul>
    <li>Execute       jk_nt_service -I &lt;name of service&gt; &lt;optional 
 params&gt; &lt;path to updated wrapper       properties&gt;</li>
    <li>&lt;name       of service&gt; should be a single word (without and 
 spaces) such as       Jakarta</li>
    <li>&lt;optional params&gt; are any of the following:</li>
    <ul>
      <li>-U &lt;user name&gt; - to set the user the service runs as. Make 
 sure the user has 'Logon as a service right'. The &lt;user name&gt; must 
be in the format DomainName\UserName (e.g. Dev\Administrator for Administrator 
 in the Dev domain or .\Administrator for the local Administrator)</li>
      <li>-P &lt;user password&gt; - Valid password for the user.</li>
      <li>-A - Sets the service to startup automatically.</li>
      <li>-D &lt;service dependancy&gt; - This sets the service that must 
 be started prior to this one. -D &lt;service dependancy&gt; can be specified 
 multiple times. &lt;service dependancy&gt; must be the 'Service Name' not 
 the 'Display Name'.<br>
      </li>
    </ul>
    <li>&lt;path       to updated wrapper properties&gt; should point to your
wrapper.properties       file (and the service will check it's existence.)</li>
    <li>For       example, valid command lines can be:</li>
    <ul>
      <li>jk_nt_service -I Jakarta wrapper.properties</li>
      <li>jk_nt_service -I Jakarta -U .\Administrator -P password -A -D MSSQLSERVER&nbsp; 
 wrapper.properties</li>
    </ul>
  </ul>
  <li>Start      tomcat as a service.</li>
  <ul>
    <li>From the command line, execute jk_nt_service -S &lt;name of service&gt; 
 &lt;optional param&gt; where &lt;optional param&gt; is:</li>
    <ul>
      <li>-M &lt;machine name&gt; - Remote machine to start the service on. 
 (e.g. jk_nt_service -S Jakarta -M DevBox)<br>
      </li>
    </ul>
    <li>From       the command line, execute net start &lt;name of service&gt; 
 (e.g. net       start Jakarta)</li>
    <li>From       the NT services applet, highlight your service and press 
 start.</li>
  </ul>
  <b>Note:</b> If the log file location in your wrapper.properties file points 
to  the <tt>logs</tt> directory, and the <tt>logs</tt> directory doesn't 
yet exist,  manually create it before starting the service.           
  <li>Stop      Tomcat as a service.</li>
  <ul>
    <li>From the command line, execute jk_nt_service -T &lt;name of service&gt; 
 &lt;optional param&gt; where &lt;optional param&gt; is:</li>
    <ul>
      <li>-M &lt;machine name&gt; - Remote machine to stop the service on. 
 (e.g. jk_nt_service -T Jakarta -M DevBox)<br>
      </li>
    </ul>
    <li>From       the command line, execute net stop &lt;name of service&gt; 
 (e.g. net       stop Jakarta)</li>
    <li>From       the NT services applet, highlight your service and press 
 stop.</li>
  </ul>
</ol>
<p><b>Special note</b>: The Tomcat service is using AJPV12 to perform clean 
 shutdown and you should make sure that an AJPV12 connector is defined in 
your server.xml. In the absence of a configured AJPV12 port the Tomcat service 
 will kill Tomcat abruptly (that is murder it) without giving it a chance 
to clean up. </p>
<p><b>Special note2</b>: Acording to  <a href="http://nagoya.apache.org/bugzilla/show_bug.cgi?id=2337%22">
    http://nagoya.apache.org/bugzilla/show_bug.cgi?id=2337</a>
   , you may have problems with long filenames. You should use the 8.3 format. 
 Thanks to Anthony Dodd for finding this workaround.</p>
<p><strong>Notice for JDK 1.3 users</strong>: There is a  <a href="http://developer.java.sun.com/developer/bugParade/bugs/4323062.html">
   known problem</a>
    in JDK 1.3 that affects Java applications being run as Windows NT services. 
 The bug causes the service to terminate when the currently logged in user 
 logs out. The simplest way to work around this problem is to use JDK 1.2. 
 If your application requires JDK 1.3 features then you  may want to look 
into <a href="http://www.kcmultimedia.com/javaserv/">javaserv</a>
    or <a href="http://www.alexandriasc.com/software/JavaService/">JavaService</a>
   . Users have reported success with both of these packages but there may
 be others that work as well. </p>
<p>To remove the installed service, execute jk_nt_service -R &lt;name of service&gt;</p>
<h1>Advance Setup</h1>
<ol>
  <li>Modify      the Tomcat NT service properties. By default the service 
 will run in manual      mode and under the local system user account. To 
modify this, open the NT      services applet, highlight your service and 
press startup. A popup window      is opened and you will be able to customize 
the service to your      satisfaction.</li>
  <li>Modify      the classpath. The classpath is determined by the wrapper.class_path
       properties, to modify it just add/remove/modify wrapper.class_path
lines.       The complete classpath is calculated by concatenating all the
     wrapper.class_path lines and putting ";" between them.</li>
  <li>Execute      several Tomcat instances. Say that you want one Tomcat 
 to run for      "production" and one for development, you can do that. All 
 you      will need to do is to install the Tomcat service twice and under 
 two      different names (and with different wrapper.properties file and 
server.xml      files). </li>
  <ul>
    <li>Make       sure that the AJPV12 and HTTP connectors are modified in
each server.xml       file to prevent a clash.</li>
    <li>Make       sure to update the wrapper.shutdown_port property in wrapper.properties
        to point to the correct AJPV12 shutdown ports (default is 8007).
    </li>
  </ul>
  <li>Modify      the command line used to start Tomcat. The Tomcat service 
 is taking all      it's command line configuration from wrapper.properties! 
 To customize the      command line, edit the property wrapper.cmd_line and 
 make sure that it      makes a legal Java command line.</li>
</ol>
<h1>Feedback</h1>
<p>Please send feedback, bug report or any additional information to <tt>
   &lt;<a href="mailto:tomcat-user@jakarta.apache.org">tomcat-user@jakarta.apache.org</a>
   &gt; </tt></p>
</body>
</html>
